package edu.mtu.citizenscience.ethnography.uploader;

import java.io.InputStream;
import java.util.Map;

import android.content.Intent;

/**
 * Defines an interface for setting up a series of REST calls
 * to the Ethnography web server.
 * @author Nicholas Blecha
 *
 */
interface EthnographyUploaderAction {
	/**
	 * Generates the data to send to the server and returns it in the form of a Map. For
	 * JSON uploads, the Map will contain all the String-Object pairs used in the JSON.
	 * For files, it contains a single mapping, FILE to a byte array with the file data.
	 * If any information is missing, returns null.
	 * 
	 * What kind of information the Map contains should be determined by checking for the key
	 * {@link EthnographyUploadAction#FILE}. If those two keys are defined, then the
	 * upload is a multipart file upload. FILE_STREAM is a key to an {@link InputStream} from which
	 * the file data should be read, and FILE_MEDIA_TYPE is a key to a string specifying the
	 * Internet Media Type of the same file.
	 * 
	 * If those two keys are not defined, the map contains key-value pairs to be used in a JSON
	 * post.
	 * 
	 * The result is undefined if {@link #hasNext()} is false.
	 * @param intent The Intent passed to start the service.
	 * @return A Map containing the data to send, or null if any extras are missing from the Intent.
	 */
	Map<String, Object> getParams(Intent intent);
	
	/**
	 * Gets the name of the resource (i.e. filename) to use for the next REST call.
	 * 
	 * The result is undefined if {@link #hasNext()} is false.
	 * @return The name of the resource to use in the next REST call.
	 */
	String getResource();
	
	/**
	 * Returns the {@link EthnographyResponseHandler} used by this action, which performs any
	 * actions necessary based on the result returned from the servicer and "advances" 
	 * this object to the next call.
	 * @return The handler used by this action
	 */
	EthnographyResponseHandler getHandler();
	
	/**
	 * Indicates if this object has more calls to make. This is always true when the object is created
	 * and is set to false when the final call returns successfully, or when any call returns with
	 * a failure. If it is false, this object cannot be used for any more calls. Its state is
	 * updated when one of the handler methods are called
	 * @return true if there are more REST calls to make, false if the sequence of REST calls
	 * is finished.
	 */
	boolean hasNext();
}
